Scenario #9033: Re Synchronizing an Existing Subject Updates Its Name Idempotently

UseCase Re Synchronize Subject Idempotently => SubjectSync: sync-alice - renamed to sync-alicia

The sync program re-synchronizes an already existing subject with the same UUID but a new name (a Keycloak rename). Because the sync program cannot know whether this backend already has the subject, adding and renaming are the same idempotent upsert: it updates the name in place, creates no second subject, and replaying the identical request is a no-op — all returning 200 OK.

Properties

Required

• SubjectSync: sync-alice from 9031: A Global Admin Can Synchronize a New User Subject

Given

name	value
subjectUuid	238a0001-0000-0000-0000-000000000001
subjectType	USER
newSubjectName	sync-alicia

Re-synchronize the subject with a new name (rename) via PUT

HTTP PUT "/api/rbac/subjects/238a0001-0000-0000-0000-000000000001" // SubjectSync: sync-alice \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "name" : "sync-alicia",
  "type" : "USER"
}
EOF
=> status: 200 OK 

Replaying the identical upsert is a no-op (idempotent)

HTTP PUT "/api/rbac/subjects/238a0001-0000-0000-0000-000000000001" // SubjectSync: sync-alice \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  -H 'Content-Type: application/json' \
  --data-binary @- <<EOF
{
  "name" : "sync-alicia",
  "type" : "USER"
}
EOF
=> status: 200 OK 

The rename did not create a second subject

HTTP GET "/api/rbac/subjects?name=sync-alicia" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }`
=> status: 200 OK 
[ {
  "uuid" : "238a0001-0000-0000-0000-000000000001", // SubjectSync: sync-alice
  "name" : "sync-alicia",
  "type" : "USER"
} ]

---

generated on 2026-07-17 01:44:28 for branch